---
type: integration
title: '@astrojs/netlify'
description: '@astrojs/netlify 어댑터를 사용하여 Astro 프로젝트를 배포하는 방법을 알아보세요.'
sidebar:
  label: Netlify
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/netlify/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';

이 어댑터를 사용하면 Astro가 [서버 아일랜드](/ko/guides/server-islands/), [액션](/ko/guides/actions/), [세션](/ko/guides/sessions/)을 포함하여 [요청 시 렌더링되는 라우트 및 기능](/ko/guides/on-demand-rendering/)을 [Netlify](https://www.netlify.com/)에 배포할 수 있습니다.

Astro를 정적 사이트 생성기로 사용하고 있다면, 서버가 필요한 추가적인 Netlify 서비스(예: [Netlify Image CDN](#netlify-이미지-cdn-지원))를 사용하는 경우에만 이 어댑터가 필요합니다. 그렇지 않다면, 정적 사이트를 배포하는 데 어댑터는 필요하지 않습니다.

[Netlify 배포 가이드](/ko/guides/deploy/netlify/)에서 Astro 사이트를 배포하는 방법을 알아보세요.

## 왜 Astro Netlify인가?

[Netlify](https://www.netlify.com/)는 GitHub 저장소에 직접 연결하여 사이트를 호스팅할 수 있는 배포 플랫폼입니다. 이 어댑터는 Astro 빌드 프로세스를 향상시켜 Netlify를 통한 배포용 프로젝트를 준비합니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

`astro add` 명령을 사용하여 Astro 프로젝트에서 요청 시 렌더링을 활성화하려면 Netlify 어댑터를 추가하세요.
그러면 `@astrojs/netlify`가 설치되고 `astro.config.mjs` 파일이 한 번에 적절하게 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add netlify
  ```
  </Fragment>
</PackageManagerTabs>

이제 [페이지별로 요청 시 렌더링](/ko/guides/on-demand-rendering/#요청-시-렌더링-활성화)을 활성화하거나, [기본적으로 모든 페이지를 서버 렌더링](/ko/guides/on-demand-rendering/#server-모드)하도록 빌드 출력 구성을 `output: 'server'`로 설정할 수 있습니다.

### 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트 종속성에 Netlify 어댑터를 설치합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/netlify
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `astro.config.*` 파일에 어댑터를 추가합니다.

```js title="astro.config.mjs" ins={2, 6}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
});
```

## 사용하기

[여기에서 전체 배포 가이드를 읽어보세요.](/ko/guides/deploy/netlify/)

지침에 따라 사이트를 [로컬로 빌드](/ko/guides/deploy/#사이트를-로컬로-빌드)하세요. 빌드 후에는 `.netlify/functions-internal/` 폴더의 [Netlify Functions](https://docs.netlify.com/functions/overview/)과 `.netlify/edge-functions/` 폴더의 [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/)을 모두 포함하는 `.netlify/` 폴더가 생성됩니다.

사이트를 배포하려면 [Netlify CLI](https://docs.netlify.com/cli/get-started/)를 설치하고 다음을 실행하세요.

```sh
netlify deploy
```

[Astro의 Netlify 블로그 게시물](https://www.netlify.com/blog/how-to-deploy-astro/)과 [Netlify 문서](https://docs.netlify.com/integrations/frameworks/astro/)는 이 통합을 사용하여 Netlify에 배포하는 방법에 대한 자세한 정보를 제공합니다.

### Edge Functions에서 Astro 미들웨어 실행

모든 Astro 미들웨어는 빌드 시 사전 렌더링된 페이지에 적용되고 런타임 시 주문형 렌더링 페이지에 적용됩니다.

사전 렌더링된 페이지에 대한 리디렉션, 액세스 제어 또는 사용자 정의 응답 헤더를 구현하려면 [`edgeMiddleware` 옵션](/ko/reference/adapter-reference/#edgemiddleware)을 활성화하여 Netlify Edge Functions에서 미들웨어를 실행하세요.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    edgeMiddleware: true,
  }),
});
```

`edgeMiddleware`가 활성화되면 에지 함수는 정적 자산, 사전 렌더링된 페이지, 주문형 렌더링된 페이지를 포함한 모든 요청에 대해 미들웨어 코드를 실행합니다.

주문형 렌더링된 페이지의 경우 `context.locals` 객체는 JSON을 사용하여 직렬화되어 렌더링을 수행하는 서버리스 함수의 헤더로 전송됩니다. 보안 조치로서 서버리스 함수는 생성된 에지 함수에서 발생하지 않는 한 `403 Forbidden` 응답이 포함된 요청 처리를 거부합니다.

### 사이트에서 에지 컨텍스트에 액세스하기

Netlify Edge Functions는 사용자 IP, 지리적 위치 데이터, 쿠키 등 요청에 대한 메타데이터를 포함하는 [컨텍스트 객체](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object)를 제공합니다.

이는 `Astro.locals.netlify.context` 객체를 통해 액세스할 수 있습니다.

```astro
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>
```

TypeScript를 사용하는 경우 `NetlifyLocals`를 사용하도록 `src/env.d.ts`를 업데이트하여 [적절한 타입](/ko/guides/typescript/#전역-타입-확장하기)을 얻을 수 있습니다.

```ts title="src/env.d.ts"
type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals;

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

사전 렌더링된 페이지에서는 사용할 수 없습니다.

### Netlify 이미지 CDN 지원

이 어댑터는 기본적으로 [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/)을 사용하여 빌드 시간에 영향을 주지 않고 즉시 이미지를 변환합니다.
내부적으로는 [Astro 이미지 서비스](/ko/reference/image-service-reference/)를 사용하여 구현됩니다.

Netlify의 Image CDN 원격 이미지 최적화를 선택 해제하려면 `imageCDN` 옵션을 사용하세요.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    imageCDN: false,
  }),
});
```

다른 도메인에서 호스팅되는 이미지를 사용하는 경우 [`image.domains`](/ko/reference/configuration-reference/#imagedomains) 또는 [`image.remotePatterns`](/ko/reference/configuration-reference/#imageremotepatterns) 구성 옵션을 사용하여 도메인 또는 URL 패턴을 승인해야 합니다.


```js title="astro.config.mjs" ins={7-9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});
```

자세한 내용은 [원격 이미지 승인 가이드](/ko/guides/images/#원격-이미지-승인)를 참조하세요. 여러분의 사이트와 동일한 도메인에 호스팅된 이미지에는 필요하지 않습니다.

### Netlify 어댑터를 사용하는 정적 사이트

Netlify에서 호스팅되는 정적 사이트 (`output: 'static'`)의 경우 일반적으로 어댑터가 필요하지 않습니다. 그러나 일부 배포 기능은 어댑터를 통해서만 사용할 수 있습니다.

Netlify의 [이미지 서비스](#netlify-이미지-cdn-지원)를 사용하고 구성하려면 정적 사이트에서 이 어댑터를 설치해야 합니다.

Astro 구성에서 `redirects` 구성을 사용하는 경우 Netlify 어댑터를 사용하여 이를 적절한 `_redirects` 형식으로 변환할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});
```

`astro build`를 실행하면 `dist/_redirects` 파일이 생성됩니다. Netlify는 이를 사용하여 프로덕션에서 페이지를 적절하게 라우팅합니다.

:::note
수동 리디렉션을 위해 `public/_redirects` 파일을 계속 포함할 수 있습니다. 리디렉션 구성에서 지정한 모든 리디렉션은 자신의 리디렉션 끝에 추가됩니다.
:::

### 세션

[Astro 세션 API](/ko/guides/sessions/)를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 환경 설정, 쇼핑 카트, 인증 자격 증명과 같은 용도로 활용될 수 있습니다. 쿠키 저장소와는 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수 있습니다.

Netlify 어댑터를 사용하는 경우 Astro는 세션 스토리지를 위해 [Netlify Blobs](https://docs.netlify.com/blobs/overview/)를 자동으로 구성합니다. 다른 세션 스토리지 드라이버를 사용하려면 Astro 구성에서 지정할 수 있습니다. 자세한 내용은 [`session` 구성 참조](/ko/reference/configuration-reference/#sessiondriver)를 확인하세요.

### 페이지 캐싱

동적 콘텐츠가 없는 주문형 렌더링 페이지를 캐시하여 성능을 향상하고 리소스 사용량을 줄일 수 있습니다.
어댑터에서 `cacheOnDemandPages` 옵션을 활성화하면 서버에서 렌더링된 모든 페이지를 최대 1년 동안 캐시합니다.

```ts title="astro.config.mjs" ins={4}
export default defineConfig({
  // ...
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});
```

응답에 캐싱 헤더를 추가하여 페이지별로 변경할 수 있습니다.

```astro title="pages/index.astro"
---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

[세밀한 캐시 제어](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/)를 통해 Netlify는 `CDN-Cache-Control` 또는 `Vary`와 같은 표준 캐싱 헤더를 지원합니다.
time to live (TTL) 또는 stale while revalidate (SWR) 캐싱 등의 구현에 대해 알아보기 위해 문서를 참조하세요: https://docs.netlify.com/platform/caching

### 스큐 보호

<p><Since v="6.6.0" pkg="@astrojs/netlify" /></p>

Netlify의 스큐 보호 기능은 배포 중에 사이트에 액세스하는 사용자가 동일한 배포 버전의 콘텐츠를 계속 받도록 보장합니다. Netlify 어댑터는 현재 배포 ID를 내부 요청에 주입하여 액션, 서버 아일랜드, 뷰 전환, 프리페치 요청과 같은 Astro 기능에 대한 스큐 보호를 자동으로 구성합니다. 이는 활성 배포 중에 클라이언트와 서버 간의 버전 불일치를 방지합니다.

Astro는 내장 기능에 대한 스큐 보호 헤더를 자동으로 추가하지만, 사이트로 직접 fetch 요청을 하는 경우에는 `DEPLOY_ID` 환경 변수를 사용하여 수동으로 헤더를 포함할 수 있습니다.

```js
const response = await fetch('/api/endpoint', {
  headers: {
    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
  },
});
```

### Netlify Functions에서 파일 포함 또는 제외하기

온디맨드 렌더링을 사용하는 Astro 사이트를 Netlify에 배포할 때, 생성된 함수는 서버 의존성을 자동으로 추적하고 포함합니다. 하지만 Netlify Functions에 포함할 파일을 사용자 정의해야 할 수 있습니다.

#### `includeFiles`

<p>
**타입:**  `string[]`<br />
**기본값:** `[]`<br />
<Since v="5.3.0" />
</p>

`includeFiles` 속성을 사용하면 함수와 함께 번들해야 하는 추가 파일을 명시적으로 지정할 수 있습니다. 이는 다음과 같이 종속성으로 자동 감지되지 않는 파일에 유용합니다:
- `fs` 연산을 사용하여 로드된 데이터 파일
- 구성 파일
- 템플릿 파일

프로젝트의 [`root`](/ko/reference/configuration-reference/#root)를 기준으로 하는 파일 경로를 사용하여 포함할 추가 파일 배열을 제공합니다. 절대 경로는 예상대로 작동하지 않을 수 있습니다.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    includeFiles: ['./my-data.json'], // `root`를 기준으로 합니다.
  }),
});
```

#### `excludeFiles`

<p>
**타입:**  `string[]`<br />
**기본값:** `[]`<br />
<Since v="5.3.0" />
</p>

`excludeFiles` 속성을 사용하여 특정 파일이 번들에 포함되지 않도록 할 수 있습니다. 이는 다음에 유용합니다:
- 번들 크기 줄이기
- 큰 바이너리 제외
- 원치 않는 파일 배포 방지

프로젝트의 [`root`](/ko/reference/configuration-reference/#root)를 기준으로 하는 파일 경로를 사용하여 제외할 특정 파일의 배열을 제공합니다. 절대 경로는 예상대로 작동하지 않을 수 있습니다.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    excludeFiles: ['./src/some_big_file.jpg'], // relative to `root`
  }),
});
```

#### glob 패턴 사용

`includeFiles`와 `excludeFiles`는 모두 여러 파일을 매치시키기 위한 [glob 패턴](/ko/guides/imports/#glob-패턴)을 지원합니다.

```js title="astro.config.mjs" ins={7, 10-11}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  adapter: netlify({
    includeFiles: [
      './data/**/*.json'
    ],
    excludeFiles: [
      './node_modules/package/**/*',
      './src/**/*.test.js'
    ]
  }),
});
```

### 로컬 개발 기능

`astro dev` 명령을 실행하면 어댑터는 여러 Netlify 플랫폼 기능을 활성화하여 환경을 프로덕션과 최대한 일치하도록 가깝게 만듭니다. 여기에는 다음이 포함됩니다.

- 로컬 [Netlify Image CDN](https://docs.netlify.com/build/image-cdn/overview/) 서버. 기본적으로 [이미지](#netlify-이미지-cdn-지원)에 사용됩니다.
- 로컬 [Netlify Blobs](https://docs.netlify.com/build/data-and-storage/netlify-blobs/) 서버. 기본적으로 [세션](#세션)에 사용됩니다.
- Netlify 구성의 [리디렉션, URL 재작성 (Rewrites)](https://docs.netlify.com/manage/routing/redirects/overview/) 및 [헤더](https://docs.netlify.com/manage/routing/headers/)
- 요청 시 렌더링되는 페이지에서 [Netlify Edge Context](#사이트에서-에지-컨텍스트에-액세스하기)에 액세스
- Netlify 사이트의 [환경 변수](https://docs.netlify.com/build/environment-variables/overview/)

로컬 사이트가 `netlify link`를 사용하여 [Netlify 사이트에 연결](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/#link-and-unlink-sites)되어 있을 때 가장 잘 작동합니다.

어댑터 구성에서 [`devFeatures`](#devfeatures) 옵션을 사용하여 이러한 기능 중 일부를 활성화 또는 비활성화할 수 있습니다. 기본적으로 환경 변수를 제외한 모든 기능이 활성화되어 있습니다.

#### `devFeatures`

<p>
**타입:** `boolean | object`<br />
**기본값:** `{ images: true, environmentVariables: false }`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

`devFeatures` 옵션은 모든 기능을 활성화 또는 비활성화하는 부울이거나 특정 기능을 활성화하는 객체일 수 있습니다.

```js title="astro.config.mjs" ins={7-12}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify({
    devFeatures: {
      // 개발 모드에서 Netlify Image CDN 지원을 활성화합니다. 기본값은 true입니다.
      images: false, 
      // 개발 모드에서 Netlify 환경 변수를 주입합니다. 기본값은 false입니다.
      environmentVariables: true, 
    },
  }),
});
```

##### `devFeatures.images`

<p>
**타입:** `boolean`<br />
**기본값:** `true`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

개발 모드에서 로컬 [Netlify Image CDN](https://docs.netlify.com/build/image-cdn/overview/) 지원을 활성화합니다.

이 경우 기본 Astro 이미지 서비스가 아닌 로컬 버전의 Netlify Image CDN을 사용합니다.

##### `devFeatures.environmentVariables`

<p>
**타입:** `boolean`<br />
**기본값:** `false`<br />
<Since v="6.5.1" pkg="@astrojs/netlify"/>
</p>

Netlify 사이트의 환경 변수를 개발 환경으로 주입합니다.

이를 통해 프로덕션 환경과 동일한 값을 개발 환경에서 사용할 수 있습니다. 환경마다 다른 변수를 사용하는 방법을 비롯한 자세한 내용은 [환경 변수에 대한 Netlify 문서](https://docs.netlify.com/build/environment-variables/overview/)를 참조하세요.

## 실험적 기능

다음 기능들도 사용 가능하지만, 향후 업데이트에서 대규모 변경 (Breaking Changes)이 발생할 수 있습니다. 프로젝트에서 이 기능을 사용 중이라면 업데이트를 위해 [`@astrojs/netlify` 변경 로그](https://github.com/withastro/astro/tree/main/packages/integrations/netlify/CHANGELOG.md)를 주의 깊게 확인하세요.

### `experimentalStaticHeaders`

<p>
  **타입:** `boolean` <br />
  **기본값:** `false`<br />
  <Since v="6.4.0"  pkg="@astrojs/netlify"/>
</p>

Netlify 구성에서 사전 렌더링된 페이지에 대한 사용자 정의 헤더를 지정할 수 있습니다.

이 기능이 활성화되면, Astro 기능 (예: 콘텐츠 보안 정책)에서 제공하는 경우 어댑터는 [정적 헤더를 프레임워크 API 구성 파일](https://docs.netlify.com/frameworks-api/#headers)에 저장합니다.

예를 들어, [실험적인 콘텐츠 보안 정책](/ko/reference/experimental-flags/csp/)이 활성화된 경우, `<meta>` 요소를 생성하는 대신 `experimentalStaticHeaders`를 사용하여 CSP `headers`를 Netlify 구성에 추가할 수 있습니다.

```js title="astro.config.mjs" {9}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: netlify({
    experimentalStaticHeaders: true 
  })
});
```

## 예시

- [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter)는 README에서 예시와 가이드를 제공합니다.

- 더 많은 예시를 보려면 [GitHub에서 Astro Netlify 프로젝트를 찾아보세요](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify&type=code)!

[astro-integration]: /ko/guides/integrations-guide/
